Cloud Connector

Introduction

The Cloud Connector provides a way for you to load data from third-party web applications into Argos or other MAPS applications. ADO, Oracle, and MSSQL data connections only support access to SQL-based data sources, and require the ability to log in directly to the database. With the Cloud Connector, you can connect to any data source that provides a RESTful API.

The data source you want to connect to might provide only an API interface, or they may also have created a preexisting web data connector for this purpose. A web data connector is an HTML file that includes JavaScript code that makes the API call to retrieve data from the external source, and then returns it in JSON format that MAPS can understand. The HTML file is hosted on a web server or other location that is visible to MAPS via a URL.

If the data source provides its own HTML interface, you can simply use its URL to create the data connection. If access is via API, a web data connector must be written to make the API call and return the data to MAPS. Once a script has been created, you then set up a Cloud Connector data connection in MAPS, which can be used in the MAPS applications just like any other data connection.

Cloud Data -> Cloud Connector -> MAPS -> Data Connection -> DataBlock and reports

Installation (MAPS Administrator)

Confirm MAPS Version

You will need to be on MAPS 6.0 or later in order to use the Cloud Connector. Your MAPS administrator should refer to the MAPS Release Documentation if an upgrade is required.

Locate Web Data Connector or Deploy Script Files

The next step is to determine where your data will be coming from, and locate an existing web data connector or create the HTML and JavaScript or other files needed to return the data in JSON format.

Test Scripts

Here are some examples of third-party connectors that you can use to test the Cloud Connector.

Deploy Script Files

Unless you are using an existing connector provided by a third party, you will need to host the HTML and JavaScript files in a location that is available from any machines from which you may be configuring the Cloud Connector.

Configure MAPS Data Connection

On the Data Connections screen in MAPS Config, create a new data connection and select Cloud Connector as the connection type.

Selecting the Cloud Connector from the list of data connection types.

Under General, enter a name for the connection to identify this Cloud Connector.

Connection Name: Earthquake USGS Cloud Connector

Go to the Driver Properties section and select the Configure Cloud Connector button at the top of the screen above the properties list.

Driver Properties tab with the Cloud Connector selected.  Properties are blank, including the address bar URL, connection data, password, username, username alias, auto refresh data, refresh interval, next refresh date, and last refresh date.

This will open a new window where you enter the Connector URL. This URL is the web address to the HTML file that you set up in the previous step. If you are using a third-party connector, this is the URL that they provide.

Cloud Connector dialog.  Connector URL: https://tableau.github.io/webdataconnector/Examples/html/earthquakeUSGS.html

After entering the URL, click the Connect button to attempt to establish a connection.

If successful, you will see the HTML page for the web data connector.

USGS Earthquake Feed dialog.  Button Get Earthquake Data.

Forecast.io Cloud Connector.  Forecast.io Weather Data.  Enter a lattitude and longitude to get localized weather data.  Latitude edit.  Longitude edit.  Need to lookup lat/long?  Try entering your address on (link) Bing Maps or put a zip code into (link) Melissa Data.  Button Get Weather Forecast.

In the examples above, selecting "Get Earthquake Data" or "Get Weather Forecast" will make a request to the third-party connector, which then returns a JSON file to MAPS. The JSON file contains the information that MAPS needs to make API calls to the connector using any specified parameters.

Driver Properties screen showing some fields filled out, including the Address Bar URL entered in the previous dialog.

To retrieve data using the connection, select the Fetch Data button under the list of properties. This will create a SQLite database on the MAPS server that contains the data returned by the API call. If successful, you will see the message "Fetch Data Completed".

MAPS Server Files

The JSON and SQLite files for each Cloud Connector are stored in the ..\MAPS\Service\WDC\Connectors folder on the MAPS server.

You can leave the other data connection properties set to their defaults.

Finally, don't forget to authorize the new data connection for use with the MAPS applications (Argos, etc.).

Authorized for user with pane showing no applications authorized.  Use the Authorize button or right-click in the pane and select Add Appliction for each application you wish to authorize.

The Cloud Connector is now ready for use.

Using the Cloud Connector Data Connection

The Cloud Connector you created can be used in the MAPS applications just like any other data connection. For example, to use this connection as the default connection for an Argos DataBlock, first select your DataBlock, and then choose the Cloud Connector connection from the Associated Connection/Group drop-down.

Associated Connection/Pool: Earthquake USGS Cloud Connector

You can use the connection data anywhere that you use SQL in Argos, such as for the report query and in dashboard objects such as list boxes, drop-downs, and charts. If you are using the Visual Designer, the Show Tables button will display the list of tables that were returned by the connection. You can then easily add the desired tables and fields to your query.

Visual Designer showing the earthquakeFeed table added to the query.  The three fields id, mag, and title have been added to the SELECT statement.

Running a report based on the query we just entered shows the data that has been brought over from the Cloud Connector:

The "Earthquake Magnitude" report lists a number of recent earthquakes by their location, magnitude, and time.

Date Formatting

When the Cloud Connector returns a date type field, MAPS is capable of parsing dates using either Julian or ISO 8601 formatting. If the date is in a different format, it may display as "12/30/1899" or possibly another incorrect date. If needed, you can use SQL to convert dates to a more appropriate format. For example, in the Visual Designer you can create a calculated field to cast the date as a varchar and then treat it as a string or perform further conversion as desired.

ISO 8601 dates can be in any of the following formats:

  • YYYY
  • YYYY-MM
  • YYYY-MM-DD
  • YYYY-MM-DDThh:mmTZD
  • YYYY-MM-DDThh:mm:ssTZD
  • YYYY-MM-DDThh:mm:ss.sTZD

'TZD' stands for Time Zone Designator, and begins with a plus or minus using one of the following formats:

  • +-hh
  • +-hh:mm